Canonical issue

Closes #1306

Outcome

GET /api/v2/videos/{video_id} no longer stalls the event loop in proportion to payload size. The handler only ever returned the parsed cache entry verbatim, so _read_video_analysis_sync now returns the entry's raw JSON bytes (read() releases the GIL) and the handler streams them back in a Response. This removes both the GIL-held json.load (~3 ms/MB, only relocated by #1304) and FastAPI's on-loop re-serialisation of the parsed dict, which paid the same size-proportional cost a second time.

Entries at or below _VALIDATION_MAX_BYTES (2 MiB — ~13× a typical one-hour transcript) are still parse-validated off-loop, so damaged entries keep surfacing as 500s. That threshold is the loop-stall bound: ~6 ms worst case, independent of video duration. Larger entries skip validation; the writer publishes atomically (temp file + os.replace), so a torn entry cannot be observed — only out-of-band corruption of an oversized entry would reach a client unflagged, accepted in exchange for the bounded stall.

The warm-cache regression disclosed in #1304 (executor hop costing more than the deferred 0.4 ms parse) is resolved by removing the parse and the on-loop re-serialisation outright; the fixed ~0.5 ms dispatch hop remains, deliberately, as insurance against unbounded filesystem latency.

Scope

• Included: _read_video_analysis_sync, the /api/v2/videos/{video_id} handler, and their tests. The characterisation test test_parse_still_stalls_the_loop_in_proportion_to_payload is replaced by its successor test_read_stall_no_longer_scales_with_payload, self-calibrated against json.loads of the same payload on the runner.
• Explicitly excluded: real_video_processor.py (held by perf: offload cache-directory scan off the event loop (#1231) #1237) — the entry-size cause (persisting the full transcript) is untouched.

Risk

• Risk level: low
• Failure mode: the response body is now the cache entry byte-for-byte instead of a re-serialised copy (semantically identical JSON; formatting/whitespace may differ). A corrupt entry above 2 MiB would be served verbatim instead of returning a 500.
• Rollback: revert the commit; the endpoint returns to parse-and-re-serialise.

Verification

• Focused tests: pytest tests/unit/test_real_api_endpoints.py — 107 passed at ec45eed, including new coverage for byte-for-byte passthrough, the inclusive validation boundary, oversized unvalidated entries, and the bounded-stall characterisation test (run 5× for flake resistance)
• Required CI
• Review threads resolved

Ruff/black were checked on the changed files; remaining findings are pre-existing in untouched regions.

Production evidence

Not applicable — backend perf change verified by the loop-gap characterisation test, which measures the stall directly against the old behaviour (json.loads of the same payload).

Agent provenance

Agent-authored via Linear agent session; run metadata is recorded in the linked Linear issue (GRV-282, agent session 36eebe27).